home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Shareware Grab Bag
/
Shareware Grab Bag.iso
/
050
/
madtrb1.arc
/
TSIPP1.DOC
< prev
next >
Wrap
Text File
|
1986-03-04
|
41KB
|
989 lines
USER'S MANUAL
------------------------------------------------------
TURBO SCREEN INPUT PRE-PROCESSOR TOOLKIT
Version 1.07
------------------------------------------------------
Written by Chris E. Maeder
March, 1986
This toolkit is PUBLIC DOMAIN. It is being distributed with the intended
purpose of other Turbo Pascal users implementing all or part of it into their
programs. It is free to anyone that wishes to use it with the hope that they
also will contribute programs to other Turbo users.
This toolkit is being continually updated. If you would like updates of this
toolkit or other free Turbo Pascal software please feel free to contact me
through:
Madison IBM-PC Users' Group
Turbo Pascal Special Interest Group
P.O. Box 2598
Madison, WI 53701-2598
I would also like to invite you to join our users' group. We are an extremely
active Turbo Pascal group and meet one night every month. If you have any
urgent questions you can reach me at my home, at (608) 251-4967.
Happy computing!!
TABLE OF CONTENTS
-----------------
Introduction...............................................1
Overview...................................................1
Software Engineering.......................................6
Shell Environments.........................................9
Notation..................................................10
Description of Toolkit Subprogram Files...................11
Description of Toolkit Utility Files......................16
Description of Files Used in the Example Application......17
Program Control...........................................19
Child Program Execution...................................20
Description of Screen Templates...........................20
Screen Template Generators................................26
Pre-Processor Alterations.................................28
Miscellaneous Notes.......................................33
Final Notes...............................................33
Page 1
I. INTRODUCTION
I am a structural engineer. I found that every time I wrote another
engineering program I would spend a week or two on the input routines. I
thought that if I were to write a generalized input pre-processor that I could
use over and over again then I could spend more time on writing engineering
programs and not rehashing through the same input routines for each new program
I wrote. This input pre-processor toolkit is the current result of my work.
The example application in which the pre-processor is set up for is a composite
beam analysis and design program that I am presently working on.
II. OVERVIEW
Good interactive input/output (I/O) routines make a program fun to use and also
make a program reliable. For example, the user should not have to worry
about crashing a program by making a simple typing mistake. Although it is
impossible for the input routines to detect all input errors, careful input
routines should catch the more common ones. A good strategy for a
"user-friendly program" is to detect input errors as soon as possible and make
it easy for the user to the correct mistakes.
An input pre-processor helps a program become "user-friendly" by taking care of
of all the input handling between the user and a application program.
A input pre-processor can be thought of as one component of an application
program. See the following diagram.
Page 2
DIAGRAM OF A SIMPLIFIED APPLICATION PROGRAM
_________________________________________________________
| |
| PROGRAM SHELL |
|_________________________________________________________|
^ ^ ^
| | |
| | |
| | |
______v______ ______v______ ______v______
| | | | | |
| INPUT | | CORE | | OUTPUT |
| PRE- | | PROGRAM | | POST- |
| PROCESSOR | | | | PROCESSOR |
|_____________| |_____________| |_____________|
^ ^ | ^
| | | |
| | | |
| | | |
__v_____ | | __v_____
_|______ | | | _|______ |
_|______ | | | | _|______ | |
| INPUT | | |-------------- ------------>| OUTPUT | | |
| DATA | |_| | DATA | |_|
| FILES |_| | FILES |_|
|________| |________|
Observe from the above diagram that the input pre-processor is the visual
interface between the user and the core program. The input pre-processor is
used by the user to input data into an application core program. The core
program then executes on that input data. A post-processor is used by the user
to view the results of the core program's output. I should note that I am
presently working on a post-processor for this toolkit.
Page 3
I have listed below some of the advantages in using an input pre-processor in
an application program like that depicted in the previous diagram:
1. To start with, breaking up a program into smaller and easier to
understand subprograms is usually the single most important
contribution to a program's quality. By using a separate subprogram to
handle user input you then separate the application program into
smaller, more manageable chunks. You will find that by separating the
user interface from the actual core program, the entire application
program begins to become more modular.
2. You will discover that your application program becomes more portable
once you have separated the user interface from the actual core
program. By "portable" I mean that the program can easily be made to
run on a variety of systems. The core program can usually be
transferred to another computer system quite easily. The user
interface usually cannot be easily transferred, because of the machine
specific routines that are generally used.
Due to the rapid advancements in technology, today's personal computers
will no doubt be obsolete within a few years. Thus a "portable"
program will have a better chance of running on future personal
computers as well as those of today, as opposed to a very machine
specific program. Simply by separating the user interface from the
core program one then needs to write a new user interface, not an
entirely new program, when transferring his program to a new computer
system.
3. Input error checking is easily implemented using an input pre-
processor. More specifically, this particular pre-processor can
check for:
a. Specific character types for an entry (i.e., positive integer,
positive real, etc.).
b. Entry is within specific defined boundaries or the entry is one
of a few select choices.
c. Newly entered boundary conditions do not corrupt previously
entered data.
Page 4
4. Probably most important, an input pre-processor makes the application
program extremely user friendly and fun to use. The user does not have
to be concerned about crashing the program if he enters a bad piece
of data, the input pre-processor will catch it for him and allow him
to return to the bad entry and change it without having to restart the
program.
5. Finally, a input pre-processor can furnish a visual interpretation of
the user's entered data. For example, a bar chart or graph could be
displayed by the input pre-processor as the user inputs data. This
allows the user some visual feedback as he enters his data, helping him
to spot input errors, trends, etc.
What makes this pre-processor so powerful is that it is written and structured
so that it can be quickly altered for a completely different application
program. A few constants require changing, the screen template files have to
be designed and written, and before you know it you have a beautiful input
pre-processor for your own application program.
Page 5
To help give you an idea how this program is structured I have shown in the
diagram below one possible configuration for this input pre-processor in an
example application.
DIAGRAM OF A TYPICAL CONFIGURATION OF THE INPUT PRE-PROCESSOR
___________________________________________________________________________
| |
| MAIN INPUT PRE-PROCESSOR PROGRAM |
|___________________________________________________________________________|
^ ^ ^
| | |
| | |
| | |
| _________ ____v_____ _____v____ _________
| _|_______ | | | | | _|_______ |
| _|_______ | | | INPUT | | MENU | _|_______ | |
| |INPUT | | |--->| PAGE |<-->| SUB- |<---|MENU | | |
| |PAGE | |_| | SUB- | | PROGRAM | |TEMPLATES| |_|
| |TEMPLATES|_| | PROGRAM | | | | |_|
| |_________| |__________| |__________| |_________|
| ^ ^ ^
| | | |
| ------------ | -------------
| | | |
| _____v____ ____v_____ ____v_____
| | | | | | |
| | SCREEN | | ERROR | | FILE |
| | I/O | | CHECKING | | I/O |
| | SUB- | | SUB- | | SUB- |
| | PROGRAM | | PROGRAM | | PROGRAM |
| |__________| |__________| |__________|
| ^
| |
| |
| |
____v_____ __v_____
| | _|______ |
| INITIL- | _|______ | |
| IZATION | | INPUT | | |
| SUB- | | DATA | |_|
| PROGRAM | | FILES |_|
|__________| |________|
Page 6
Notice in the previous diagram this input pre-processor toolkit is broken down
into subprogram files. These subprogram files are mainly made up with program
modules to afford program modularity.
III. SOFTWARE ENGINEERING
Let me talk a little bit about program modules and why they are so useful in
writing code for a large program.
One can think of a module as a type of black box, it does one thing and one
thing alone and does it very well and everything it requires is contained
within it.
A module should be a small, single purpose unit within the program, with a
narrow interface to the rest of the program. I say this because it is much
easier to understand and change a small, single purpose module than a large,
multipurpose, widely-interfaced one. Also, a should module hide its design
from the rest of the program, so that only the module is affected if the
programmer decides to revise the module's design.
There is only one way to access a given module and that is through it's header.
A specific set of parameters are passed to a module and a specific set of
output parameters are returned. Note that functions and procedures within a
module cannot be accessed externally. Also, modules allow the use of internal
global variables within that particular module alone.
Page 7
A module is constructed by encapsuling all the procedures, functions, and
internal global variables for that module within one main procedure (using one
lexical level). See below diagram.
EXAMPLE MODULE
Procedure DoItModule( FirstParameter,
SecondParameter,
Var ThirdParameter:ParameterType);
Var
InternalGlobalVar:VarType;
Function DoItQuick;
Begin { DoItQuick }
.
.
.
End; { DoItQuick }
Procedure DoItGood;
Begin { DoItGood }
.
.
.
End; { DoItGood }
Begin { DoItModule }
.
.
.
End; { DoItModule }
Page 8
Notice in the previous example that the module's input parameters were
"FirstParameter", "SecondParameter", and "ThirdParameter". Similarly, the
module's output parameter was "ThirdParameter". The above module has it own
internal global variable called "InternalGlobalVar". This variable is only
active within the module and is global to all the functions and procedures
within the module. Observe also that the functions and procedures within the
module can only be accessed when the module as a whole is accessed.
Modules offer some very nice advantages when writing code for a large program.
1. First, modules help to minimize the amount of code the programmer needs
to understand at one given instant. A module can be studied and
changed without examining and/or re-writing the rest of the program.
This is a great aid in debugging and modifying a program since once a
module is debugged it usually can be treated as a "given" while the
rest of the program is examined.
2. One will find that many times major changes are necessary in a program
due to errors, changes in requirements, etc. These changes can have a
widespread effect on the program if they were not anticipated ahead of
time in the original program design. Thus we see that modularity helps
to limit the "rippling effect" through a program as other parts in the
main program change.
3. Finally, modularity usually results in decreased programming time for
programs written later on. Some modules often can be reused in a
number of programs, thereby preventing having to "re-invent the wheel".
A word of wisdom--try to keep modules as flexible as possible so they will
remain usable in a variety of situations, not just for the one for which they
were first written for.
For those of you who are interested, we've been talking about one small area
in the subject of software engineering, a new and very exciting computer
science subject.
Page 9
IV. SHELL ENVIRONMENTS
I would like you to note that you can use this pre-processor as part of a
shell environment (like TopView without the multi-tasking capability).
This toolkit contains routines that allow this pre-processor to operate as
part of a parent program written in Turbo Pascal, calling another program
(written in a different language, i.e. C, Fortran, compiled Basic, etc.) as a
child program. Control is passed to the child program and then returned back
to the Turbo program, (see the previous diagram of a simplified application
program). I will give an example.
There are many good, debugged structural analysis and design programs written
in Fortran. Usually though, the user interface in Fortran programs are pretty
bad. Thus, I could write a Turbo shell program (called the parent program)
that incorporated this pre-processor and a post-processor (yet to be written),
and a Fortran program. I would then use the pre-processor in this shell
environment to generate the proper input files for the Fortran program (called
the child program) and then pass control to that Fortran program. The user
would be totally unaware that control was passed to a different program.
The Fortran program would then read the input file, execute on it, and write
the output to a file. Control would then be passed back to the Turbo program,
specifically to the next line of Pascal code. The post-processor might take
over now and graphically display the Fortran program's results. Thus there
would never be any need to re-write the existing debugged Fortran program into
Pascal. One simply would have to be certain that the input file was written in
the proper format for the Fortran program to read and what the Fortran output
file format was for the post-processor to read.
One could also place several existing programs under the same shell
environment, treating them all as "core programs", passing control back and
forth between various core programs as deemed necessary. Some sort a data
management would probably be required for transferring the data in the proper
format to the various core programs.
Page 10
V. NOTATION
A few notes on my variable naming notation:
"G_I" means General Input
"S_I" means Scrolling Input
All constants are in uppercase with underscore characters between words. All
variables, functions, and procedure names are in lower case with a capital
letter at the start of each word within the name, with no underscore between
words. I recommend that you adopt a similar notation if you already haven't.
It is very helpful to be able to look at your code and be able to tell what
identifiers are constants.
A few notes on my file naming notation:
"Col" means Color
"Doc" means Documentation
"Frm" means Form
"Gen" means Generator
"Inc" means Include File
"Mon" means Monochrome
"Pas" means Pascal
"Tpl" means Template
"Tsipp" means Turbo Screen Input Pre-Processor
Page 11
VI. DESCRIPTION OF TOOLKIT SUBPROGRAM FILES
Below is an alphabetical list of the pre-processor subprogram include files you
will find in this toolkit along with a short description on what each
subprogram does.
File Description
----------- -----------------------------------------------------------
Display.Inc This include file contains a subprogram for displaying the
input data in the scrolling input pages in a more
meaningful way. The example application of the input pre-
processor is set-up so that a model of the user's entered
beam load is displayed. You may want to implement a
similar type of display to represent your user's entered
data.
For example, you may want to display a graph, bar chart,
etc. I wrote this subprogram so that the user could see a
visual representation of the input data as he was
entering it. This enables the user to be able to spot
input errors more easily, trends, etc. This subprogram
file tries to help to reduce the possibility of "Garbage
In = Garbage Out".
Error.Inc This include file contains the input error checking
subprogram. This subprogram contains two modules which are
called after a user has entered a data entry. One module
is for input error checking for the general input
subprogram, the other is for input error checking for the
scrolling input subprogram. Both of these two modules can
determine if a specific input data entry is within the
prescribed bounds allowed or is one of a few predetermined
choices. These modules also make certain that newly
entered boundary conditions do not corrupt previously
entered data. This subprogram file tries to prevent
"Garbage In = Garbage Out". You may want to write similar
modules for your application program to check the user's
input data as it is entered.
Note that specific error character type checking is
performed in "G_Input.Inc" and "S_Input2.Inc", not in this
subprogram. It is always good strategy to check for input
errors as soon as possible. That is why character type
checking is linked with the screen templates and general
input subprogram or scrolling input subprogram.
Page 12
Execute.Inc This include file contains the subprogram that allows you
to run child programs directly from Turbo Pascal, get the
return codes from DOS when those child programs terminate,
and be able to temporarily exit your Turbo program to issue
DOS commands.
One could write a Turbo shell program to execute other
programs using these routines, thereby relieving the user
from having to deal with DOS. These routines are very
powerful for a large application program, especially if you
want to take existing programs and get them running all
under the same program shell.
File.Inc This include file contains the file I/O subprogram. This
subprogram contains three modules of interest.
One module takes care of the reading of previously prepared
input data files.
The second module takes care of the writing of the input
data to a data file.
The input pre-processor was setup to allow the user to work
on his input data for a while, store it under a file name
and come back to it later to make changes, etc.
You may, for example, want the input data to be written in
a specific format (such as if you wanted the input file to
be read by a Fortran program). In this subprogram you
should write a small procedure to write a temporary ASCII
text file with the proper format for the core program
to read and execute on. This file should be separate of
the user's input data file.
The last module controls the displaying and listing of the
disk directory. This allows the user to query the input
pre-processor for a list of previously prepared input data
files.
One final note, the user is not allowed to specify the
input data file name extension. This was done to simplify
the file I/O routines for the user. That way the user does
not have to guess what files are input files since the
program will only recognize those data files with the
proper extension. The pre-processor will only read, write,
or display input data files with the same file name
extension.
Page 13
Init.Inc This include file contains the initialization subprogram
for the input pre-processor. This subprogram senses what
type of monitor and video card is installed, controls the
reading of the screen template files, screen page files,
initializes all data entries and variables, and sets up the
proper screen colors for the type of monitor being used.
G_Input.Inc This include file contains the general input page
subprogram. This subprogram controls the entering of data
into the general input pages. This subprogram will support
as many general input pages as you require. Notice that
there is only one general input page in the example
application of the input pre-processor.
This subprogram checks data entered by the user to make
certain it is of the type defined in the screen template
for that entry. For example, if only a positive integer is
to be allowed for a particular entry, only that data type
will be allowed to be entered from the keyboard. All other
characters will be discarded with an error sounded also.
Entry descriptors (or prompts) are easily added, deleted,
or altered using "G_I_Tpl.Gen" to generate or change a
screen template. Descriptor locations, entry locations,
entry types, etc. are set up in the template file and the
general input page subprogram then abides by the template
you have defined.
Global constants, types, and variables specific to this
subprogram are also defined within this file.
Menu.Inc This include file contains the menu page subprogram. This
subprogram controls the display and handling of menus.
This subprogram's routines allow you to manage as many
menus as your particular application requires. Notice that
there is only one menu page in the example application of
the input pre-processor.
You may, for example, want to implement a menu to allow the
user to transfer control to another part of the application
program or to an entirely different program (as what could
be done with the overlay, chain, or execute statement, or
with the included subprogram "Execute.Inc").
Page 14
Menu prompts are easily added, deleted, or altered using
"Menu_Tpl.Gen" to generate or change a menu screen
template. Menu prompt locations, menu prompts, etc. are
setup in the template file and the menu subprogram then
abides by that particular menu page screen template which
you have defined.
Global constants, types, and variables specific to this
subprogram are defined also within this file.
S_Input1.Inc These two include files contain the scrolling input page
S_Input2.Inc subprogram. This subprogram controls the entering of data
into the scrolling input pages. This subprogram will
support as many scrolling input pages as you require.
Notice that there are 4 scrolling input pages in the
example application of the input pre-processor: uniform
beam loading, concentrated beam loading, prismatic beam
loading, and applied moments to a beam.
Notice that the routines within this subprogram allow many
more entry rows and entry columns to be displayed within
the scrolling input window than can actually physically
fit. It does this by scrolling the rows up and down and
the columns left and right within the scroll window. Thus
the scrolling input window acts much like a view port onto
a spreadsheet.
Column headings (or prompts) are easily added, deleted, or
altered using "S_I_Tpl.Gen" to generate or change a column
heading template file. Input data type definitions for
each particular scroll column are also defined in the
column heading template.
The size and/or placement of the scrolling input window can
be easily changed.
This subprogram also checks the input data as it is entered
by the user, sounding an error when characters of the wrong
type are entered.
Global constants, types, and variables specific to this
subprogram are defined within "S_Input1.Inc".
Page 15
Screen.Inc This include file is a subprogram (or library) of some
very sophisticated screen I/O routines. These routines
vary from zooming a window onto the screen to taking a
snapshot of the screen and storing it in the heap for later
display.
Below is an alphabetical list of the functions and
procedures contained in this subprogram include file.
Date1 Date2
DisplayScreenPage DrawHorizWindowLine2
DrawHorizWindowLine1 DrawWindow1
DrawWindow2 HideBlinkingCursor
InitTextScreenPointers MonitorType
ReadScreenPagesFromFile RecallTextScreen
SetCursorSize ShowBlinkingCursor
SoundAttention SoundError
SpeedPrint SpeedPrint2
StoreTextScreen Time
WaitUntilKeypressed WriteCenterText
WriteScreenPageToFile ZoomWindow1
ZoomWindow2
Note that some of these routines are not used in the pre-
processor. You can therefore reduce the size of your "Com"
file by only including those routines within this include
file that you are going to use in your program.
Tsipp1.Doc The toolkit documentation files.
Tsipp2.Doc
Tsipp.Pas This file should be the one you start compilation with.
This is the main program file which makes all the include
calls for the other subprogram files and the required
forward references to later functions and procedures. Some
global constants, types, and variables are defined in this
file. "Tsipp" stands for "Turbo Screen Input Pre-
Processor".
These include files are modular in design. Thus you should exclude those files
from compilation that you do not need. For example, if your particular
application of this pre-processor does not require scrolling input windows,
then do not include the files "S_Input1.Inc", "S_Input2.Inc", and
"Display.Inc".
Page 16
VII. DESCRIPTION OF TOOLKIT UTILITY FILES
Below is an alphabetical list of the pre-processor toolkit utility files you
will find in this toolkit along with a short description on what each utility
does.
File Description
----------- -----------------------------------------------------------
G_I_Tpl.Frm This is a template form that you can use to help plan out
your general input page screen template. It lists out all
the items that need to be inserted into the template file
in the proper format. Simply print the template form out
with your printer. I recommend that you set your printer
to print in compressed mode before printing out this file
since the template form is 125 characters wide.
G_I_Tpl.Gen This is a short program that is used to generate the
general input page screen templates. The general input
page screen template stores all the data input descriptors
and related information for a particular general input
page.
Menu_Tpl.Frm This is a template form that you can use to help plan a
menu screen template. It lists out all the items that
need to be inserted into the template file in the proper
format. Simply print the template form out with your
printer. I recommend that you set your printer to print in
compressed mode before printing out this file since the
template form is 125 characters wide.
Menu_Tpl.Gen This is a short program that is used to generate the menu
screen templates. The menu screen template stores all the
menu prompts and related data for a particular menu page.
S_I_Tpl.Frm This is a template form that you can use to help plan out
your scrolling input page column heading template. It
lists out all the items that need to be inserted into the
template file in the proper format to display individual
column headings. Simply print the template form out with
your printer. I recommend that you set your printer to
print in compressed mode before printing out this file
since the template form is 125 characters wide.
Page 17
S_I_Tpl.Gen This is a short program that is used to generate the
scrolling input column heading template file for all the
scrolling input windows.
Notice that only one scrolling input column heading
template file is required to store the required information
for as many scrolling input pages as you require, while all
the other templates (i.e. General Input, Menu) are for only
one specific page.
VIII. DESCRIPTION OF FILES USED IN THE EXAMPLE APPLICATION
Below is an alphabetical list of the files used in the example application of
the input pre-processor you will find in this toolkit along with a short
description on what each file is.
File Description
----------- -----------------------------------------------------------
Example.Com A compiled and ready to run example application using the
turbo screen input pre-processor toolkit. It has complete
error checking and windows implemented.
G_I_01.Col A color screen file for general input page 1 in the
example application program.
G_I_01.Mon A monochrome screen file for general input page 1 in the
example application program.
G_I_01.Tpl This is a general input page screen template file that I
generated using the "G_I_Tpl.Gen" to give an example on how
the input pre-processor works.
Menu_01.Col A color screen file for menu page 1 for the example
application program.
Page 18
Menu_01.Mon A monochrome screen file for menu page 1 in the
example application program.
Menu_01.Tpl This is a menu screen template file that I generated using
the "Menu_Tpl.Gen" to give an example on how the input
pre-processor works.
S_I_01.Col A color screen file for scrolling input page 1 in the
example application program.
S_I_02.Col A color screen file for scrolling input page 2 in the
example application program.
S_I_03.Col A color screen file for scrolling input page 3 in the
example application program.
S_I_04.Col A color screen file for scrolling input page 4 in the
example application program.
S_I_01.Mon A monochrome screen file for scrolling input page 1 in
the example application program.
S_I_02.Mon A monochrome screen file for scrolling input page 2 in the
example application program.
S_I_03.Mon A monochrome screen file for scrolling input page 3 in
the example application program.
S_I_04.Mon A monochrome screen file for scrolling input page 4 in the
example application program.
S_Input.Tpl This is a scrolling input page column prompt template that
I generated using the "S_I_Tpl.Gen" to give an example on
how the input pre-processor works. Notice that this one
template file stores the required information for as many
scrolling input pages as you require, while all the other
templates are for only one specific page.
Page 19
Test1.Inp A sample input data file for the above example application.
Test2.Inp A sample input data file for the above example application.
Now let me explain a little more on the specifics of how the Turbo Screen
Input Pre-processor works and what you need to know to easily alter it for your
own application.
IX. PROGRAM CONTROL
During execution of the input pre-processor program control is passed between
three subprograms--general input, menu, and scrolling input. For the input
pre-processor main program to know which input subprogram currently has
control, the enumerated page control variable CurrentPage is used.
Type
PageType=(Menu,G_I,S_I,Exit);
{ Enumerated data type used to tell the main program which }
{ of the below page type subprograms is currently in }
{ control: }
{ Menu Subprogram }
{ General Input Subprogram }
{ Scrolling Input Subprogram }
{ Exit back to the operating system }
Var
CurrentPage:PageType;
{ A variable used to tell the main program what }
{ input page subprogram is currently in control. }
